'\" te
.\"  Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DDI_ADD_INTR 9F "March 6, 2023"
.SH NAME
ddi_add_intr, ddi_get_iblock_cookie, ddi_remove_intr \- hardware interrupt
handling routines
.SH SYNOPSIS
.nf
#include <sys/types.h>
#include <sys/conf.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_get_iblock_cookie\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR,
      \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_add_intr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR,
     \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR,
     \fBddi_idevice_cookie_t *\fR\fIidevice_cookiep\fR,
     \fBuint_t (*\fR\fIint_handler\fR) (caddr_t),
     \fBcaddr_t\fR \fIint_handler_arg\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_remove_intr\fR(\fBdev_info_t *\fR\fIdip\fR,
     \fBuint_t\fR \fIinumber\fR, \fBddi_iblock_cookie_t\fR \fIiblock_cookie\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI). These interfaces are obsolete. Use the new
interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device
Drivers\fR for more information.
.SH PARAMETERS
For \fBddi_get_iblock_cookie()\fR:
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 18n
Pointer to \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIinumber\fR\fR
.ad
.RS 18n
Interrupt number.
.RE

.sp
.ne 2
.na
\fB\fIiblock_cookiep\fR\fR
.ad
.RS 18n
Pointer to an interrupt block cookie.
.RE

.sp
.LP
For \fBddi_add_intr()\fR:
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 19n
Pointer to \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIinumber\fR\fR
.ad
.RS 19n
Interrupt number.
.RE

.sp
.ne 2
.na
\fB\fIiblock_cookiep\fR\fR
.ad
.RS 19n
Optional pointer to an interrupt block cookie where a returned interrupt block
cookie is stored.
.RE

.sp
.ne 2
.na
\fB\fIidevice_cookiep\fR\fR
.ad
.RS 19n
Optional pointer to an interrupt device cookie where a returned interrupt
device cookie is stored.
.RE

.sp
.ne 2
.na
\fB\fIint_handler\fR\fR
.ad
.RS 19n
Pointer to interrupt handler.
.RE

.sp
.ne 2
.na
\fB\fIint_handler_arg\fR\fR
.ad
.RS 19n
Argument for interrupt handler.
.RE

.sp
.LP
For \fBddi_remove_intr()\fR:
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 17n
Pointer to \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIinumber\fR\fR
.ad
.RS 17n
Interrupt number.
.RE

.sp
.ne 2
.na
\fB\fIiblock_cookie\fR\fR
.ad
.RS 17n
Block cookie which identifies the interrupt handler to be removed.
.RE

.SH DESCRIPTION
.SS "ddi_get_iblock_cookie(\|)"
\fBddi_get_iblock_cookie()\fR retrieves the interrupt block cookie associated
with a particular interrupt specification. This routine should be called before
\fBddi_add_intr()\fR to retrieve the interrupt block cookie needed to
initialize locks (\fBmutex\fR(9F), \fBrwlock\fR(9F)) used by the interrupt
routine. The interrupt number \fIinumber\fR determines for which interrupt
specification to retrieve the cookie. \fIinumber\fR is associated with
information provided either by the device or the hardware
configuration file (see \fBsysbus\fR(5), \fBisa\fR(5), and
\fBdriver.conf\fR(5)). If only one interrupt is associated with the device,
\fIinumber\fR should be \fB0\fR.
.sp
.LP
On a successful return, \fI*iblock_cookiep\fR contains information needed for
initializing locks associated with the interrupt specification corresponding to
\fIinumber\fR (see \fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). The driver can
then initialize locks acquired by the interrupt routine before calling
\fBddi_add_intr()\fR which prevents a possible race condition where the
driver's interrupt handler is called immediately \fBafter\fR the driver has
called \fBddi_add_intr()\fR but \fBbefore\fR the driver has initialized the
locks. This may happen when an interrupt for a different device occurs on the
same interrupt level. If the interrupt routine acquires the lock before the
lock has been initialized, undefined behavior may result.
.SS "ddi_add_intr(\|)"
\fBddi_add_intr()\fR adds an interrupt handler to the system. The interrupt
number \fIinumber\fR determines which interrupt the handler will be associated
with. (Refer to \fBddi_get_iblock_cookie()\fR above.)
.sp
.LP
On a successful return, \fIiblock_cookiep\fR contains information used for
initializing locks associated with this interrupt specification (see
\fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). Note that the interrupt block
cookie is usually obtained using \fBddi_get_iblock_cookie()\fR to avoid the
race conditions described above (refer to \fBddi_get_iblock_cookie()\fR above).
For this reason, \fIiblock_cookiep\fR is no longer useful and should be set to
\fINULL\fR.
.sp
.LP
On a successful return, \fIidevice_cookiep\fR contains a pointer to a
\fBddi_idevice_cookie_t\fR structure (see \fBddi_idevice_cookie\fR(9S))
containing information useful for some devices that have programmable
interrupts. If \fIidevice_cookiep\fR is set to \fINULL\fR, no value is
returned.
.sp
.LP
The routine \fIintr_handler\fR, with its argument \fIint_handler_arg\fR, is
called upon receipt of the appropriate interrupt. The interrupt handler should
return \fBDDI_INTR_CLAIMED\fR if the interrupt was claimed,
\fBDDI_INTR_UNCLAIMED\fR otherwise.
.sp
.LP
If successful, \fBddi_add_intr()\fR returns \fBDDI_SUCCESS\fR. If the interrupt
information cannot be found on the sun4u architecture, either
\fBDDI_INTR_NOTFOUND\fR or \fBDDI_FAILURE\fR can be returned. On i86pc and
sun4m architectures, if the interrupt information cannot be found,
\fBDDI_INTR_NOTFOUND\fR is returned.
.SS "ddi_remove_intr(\|)"
\fBddi_remove_intr()\fR removes an interrupt handler from the system.
Unloadable drivers should call this routine during their \fBdetach\fR(9E)
routine to remove their interrupt handler from the system.
.sp
.LP
The device interrupt routine for this instance of the device will not execute
after \fBddi_remove_intr()\fR returns. \fBddi_remove_intr()\fR may need to wait
for the device interrupt routine to complete before returning. Therefore, locks
acquired by the interrupt handler should not be held across the call to
\fBddi_remove_intr()\fR or deadlock may result.
.SS "For All Three Functions:"
For certain bus types, you can call these \fBDDI\fR functions from a
high-interrupt context. These types include \fBISA\fR buses. See
\fBsysbus\fR(5) and \fBisa\fR(5) for details.
.SH RETURN VALUES
\fBddi_add_intr()\fR and \fBddi_get_iblock_cookie()\fR return:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 21n
On success.
.RE

.sp
.ne 2
.na
\fB\fBDDI_INTR_NOTFOUND\fR\fR
.ad
.RS 21n
On failure to find the interrupt.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 21n
On failure. \fBDDI_FAILURE\fR can also be returned on failure to find interrupt
(\fBsun4u\fR).
.RE

.SH CONTEXT
\fBddi_add_intr()\fR, \fBddi_remove_intr()\fR, and
\fBddi_get_iblock_cookie()\fR can be called from user or kernel context.
.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Obsolete
.TE

.SH SEE ALSO
.BR driver.conf (5),
.BR isa (5),
.BR sysbus (5),
.BR attach (9E),
.BR detach (9E),
.BR Intro (9F),
.BR ddi_intr_hilevel (9F),
.BR mutex (9F),
.BR mutex_init (9F),
.BR rw_init (9F),
.BR rwlock (9F),
.BR ddi_idevice_cookie (9S)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
\fBddi_get_iblock_cookie()\fR must not be called \fBafter\fR the driver adds an
interrupt handler for the interrupt specification corresponding to
\fIinumber\fR.
.sp
.LP
All consumers of these interfaces, checking return codes, should verify
\fBreturn_code != DDI_SUCCESS\fR. Checking for specific failure codes can
result in inconsistent behaviors among platforms.
.SH BUGS
The \fIidevice_cookiep\fR should really point to a data structure that is
specific to the bus architecture that the device operates on.
